Move documentation to inline comments: GtkMenuItem

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 12b97aeb0b29a987598f637f92dd9207d78fd958..997eb9e0f63478aa25ab6f74278342e58cec1235 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -71,6 +71,7 @@ gtkliststore.sgml
 gtkmain.sgml
 gtkmenu.sgml
 gtkmenubar.sgml
+gtkmenuitem.sgml
 gtkmenushell.sgml
 gtkmenutoolbutton.sgml
 gtkmessagedialog.sgml

diff --git a/docs/reference/gtk/tmpl/gtkmenuitem.sgml b/docs/reference/gtk/tmpl/gtkmenuitem.sgml
deleted file mode 100644 (file)
index 881646e..0000000
--- a/docs/reference/gtk/tmpl/gtkmenuitem.sgml
+++ /dev/null
@@ -1,344 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkMenuItem
-
-<!-- ##### SECTION Short_Description ##### -->
-The widget used for item in menus
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GtkMenuItem widget and the derived widgets are the only valid
-childs for menus. Their function is to correctly handle highlighting,
-alignment, events and submenus.
-</para>
-<para>
-As it derives from #GtkBin it can hold any valid child widget, altough
-only a few are really useful.
-</para>
-<refsect2 id="GtkMenuItem-BUILDER-UI">
-<title>GtkMenuItem as GtkBuildable</title>
-<para>
-The GtkMenuItem implementation of the GtkBuildable interface
-supports adding a submenu by specifying "submenu" as the "type" 
-attribute of a &lt;child&gt; element.
-</para>
-<example>
-<title>A UI definition fragment with submenus</title>
-<programlisting><![CDATA[
-<object class="GtkMenuItem">
-  <child type="submenu">
-    <object class="GtkMenu"/>
-  </child>
-</object>
-]]></programlisting>
-</example>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-<variablelist>
-<varlistentry>
-<term>#GtkBin</term>
-<listitem><para>for how to handle the child.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>#GtkItem</term>
-<listitem><para>is the abstract class for all sorts of items.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>#GtkMenuShell</term>
-<listitem><para>is always the parent of #GtkMenuItem.</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkMenuItem ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkMenuItem::activate ##### -->
-<para>
-Emitted when the item is activated.
-</para>
-
-@menuitem: the object which received the signal.
-
-<!-- ##### SIGNAL GtkMenuItem::activate-item ##### -->
-<para>
-Emitted when the item is activated, but also if the menu item has a
-submenu. For normal applications, the relevant signal is "activate".
-</para>
-
-@menuitem: the object which received the signal.
-
-<!-- ##### SIGNAL GtkMenuItem::deselect ##### -->
-<para>
-
-</para>
-
-@menuitem: the object which received the signal.
-
-<!-- ##### SIGNAL GtkMenuItem::select ##### -->
-<para>
-
-</para>
-
-@menuitem: the object which received the signal.
-
-<!-- ##### SIGNAL GtkMenuItem::toggle-size-allocate ##### -->
-<para>
-
-</para>
-
-@menuitem: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkMenuItem::toggle-size-request ##### -->
-<para>
-
-</para>
-
-@menuitem: the object which received the signal.
-@arg1: 
-
-<!-- ##### ARG GtkMenuItem:accel-path ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:right-justified ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:submenu ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:use-underline ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:arrow-scaling ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:arrow-spacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:horizontal-padding ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:selected-shadow-type ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:toggle-spacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenuItem:width-chars ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_menu_item_new ##### -->
-<para>
-Creates a new #GtkMenuItem.
-</para>
-
-@void: 
-@Returns: the newly created #GtkMenuItem
-
-
-<!-- ##### FUNCTION gtk_menu_item_new_with_label ##### -->
-<para>
-Creates a new #GtkMenuItem whose child is a #GtkLabel.
-</para>
-
-@label: the text for the label
-@Returns: the newly created #GtkMenuItem
-
-
-<!-- ##### FUNCTION gtk_menu_item_new_with_mnemonic ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_set_right_justified ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@right_justified: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_get_right_justified ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_get_label ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_set_label ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@label: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_get_use_underline ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_set_use_underline ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@setting: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_set_submenu ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@submenu: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_get_submenu ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_set_accel_path ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@accel_path: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_get_accel_path ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_select ##### -->
-<para>
-Emits the "select" signal on the given item. Behaves exactly like
-#gtk_item_select.
-</para>
-
-@menu_item: the menu item
-
-
-<!-- ##### FUNCTION gtk_menu_item_deselect ##### -->
-<para>
-Emits the "deselect" signal on the given item. Behaves exactly like
-#gtk_item_deselect.
-</para>
-
-@menu_item: the menu item
-
-
-<!-- ##### FUNCTION gtk_menu_item_activate ##### -->
-<para>
-Emits the "activate" signal on the given item
-</para>
-
-@menu_item: the menu item
-
-
-<!-- ##### FUNCTION gtk_menu_item_toggle_size_request ##### -->
-<para>
-Emits the "toggle_size_request" signal on the given item.
-</para>
-
-@menu_item: the menu item
-@requisition: the requisition to use as signal data.
-
-
-<!-- ##### FUNCTION gtk_menu_item_toggle_size_allocate ##### -->
-<para>
-Emits the "toggle_size_allocate" signal on the given item.
-</para>
-
-@menu_item: the menu item.
-@allocation: the allocation to use as signal data.
-
-
-<!-- ##### FUNCTION gtk_menu_item_get_reserve_indicator ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_menu_item_set_reserve_indicator ##### -->
-<para>
-
-</para>
-
-@menu_item: 
-@reserve: 
-
-

diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 72fbe4227bcff7ab5a0ff7adbff6ddf15104038c..618ebab8bbb714003fde4a3d4095c036ebfc43d1 100644 (file)
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -44,6 +44,38 @@
 #include "gtktypebuiltins.h"
 
 
+/**
+ * SECTION:gtkmenuitem
+ * @Short_description: The widget used for item in menus
+ * @Title: GtkMenuItem
+ * @See_also: #GtkBin, #GtkItem, #GtkMenuShell
+ *
+ * The #GtkMenuItem widget and the derived widgets are the only valid
+ * childs for menus. Their function is to correctly handle highlighting,
+ * alignment, events and submenus.
+ *
+ * As it derives from #GtkBin it can hold any valid child widget, altough
+ * only a few are really useful.
+ *
+ * <refsect2 id="GtkMenuItem-BUILDER-UI">
+ * <title>GtkMenuItem as GtkBuildable</title>
+ * The GtkMenuItem implementation of the GtkBuildable interface
+ * supports adding a submenu by specifying "submenu" as the "type"
+ * attribute of a &lt;child&gt; element.
+ * <example>
+ * <title>A UI definition fragment with submenus</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkMenuItem">
+ *   <child type="submenu">
+ *     <object class="GtkMenu"/>
+ *   </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </refsect2>
+ */
+
+
 enum {
   ACTIVATE,
   ACTIVATE_ITEM,
@@ -210,6 +242,12 @@ gtk_menu_item_class_init (GtkMenuItemClass *klass)
 
   klass->hide_on_activate = TRUE;
 
+  /**
+   * GtkMenuItem::activate:
+   * @menuitem: the object which received the signal.
+   *
+   * Emitted when the item is activated.
+   */
   menu_item_signals[ACTIVATE] =
     g_signal_new (I_("activate"),
                   G_OBJECT_CLASS_TYPE (gobject_class),
@@ -220,6 +258,14 @@ gtk_menu_item_class_init (GtkMenuItemClass *klass)
                   G_TYPE_NONE, 0);
   widget_class->activate_signal = menu_item_signals[ACTIVATE];
 
+  /**
+   * GtkMenuItem::activate-item:
+   * @menuitem: the object which received the signal.
+   *
+   * Emitted when the item is activated, but also if the menu item has a
+   * submenu. For normal applications, the relevant signal is
+   * #GtkMenuItem::activate.
+   */
   menu_item_signals[ACTIVATE_ITEM] =
     g_signal_new (I_("activate-item"),
                   G_OBJECT_CLASS_TYPE (gobject_class),
@@ -443,12 +489,27 @@ gtk_menu_item_init (GtkMenuItem *menu_item)
   gtk_style_context_add_class (context, GTK_STYLE_CLASS_MENUITEM);
 }
 
+/**
+ * gtk_menu_item_new:
+ *
+ * Creates a new #GtkMenuItem.
+ *
+ * Returns: the newly created #GtkMenuItem
+ */
 GtkWidget*
 gtk_menu_item_new (void)
 {
   return g_object_new (GTK_TYPE_MENU_ITEM, NULL);
 }
 
+/**
+ * gtk_menu_item_new_with_label:
+ * @label: the text for the label
+ *
+ * Creates a new #GtkMenuItem whose child is a #GtkLabel.
+ *
+ * Returns: the newly created #GtkMenuItem
+ */
 GtkWidget*
 gtk_menu_item_new_with_label (const gchar *label)
 {
@@ -1301,6 +1362,13 @@ gtk_menu_item_select (GtkMenuItem *menu_item)
     }
 }
 
+/**
+ * gtk_menu_item_deselect:
+ * @menu_item: the menu item
+ *
+ * Emits the #GtkMenuItem::deselect signal on the given item. Behaves
+ * exactly like #gtk_item_deselect.
+ */
 void
 gtk_menu_item_deselect (GtkMenuItem *menu_item)
 {
@@ -1323,6 +1391,12 @@ gtk_menu_item_deselect (GtkMenuItem *menu_item)
     }
 }
 
+/**
+ * gtk_menu_item_activate:
+ * @menu_item: the menu item
+ *
+ * Emits the #GtkMenuItem::activate signal on the given item
+ */
 void
 gtk_menu_item_activate (GtkMenuItem *menu_item)
 {
@@ -1331,6 +1405,13 @@ gtk_menu_item_activate (GtkMenuItem *menu_item)
   g_signal_emit (menu_item, menu_item_signals[ACTIVATE], 0);
 }
 
+/**
+ * gtk_menu_item_toggle_size_request:
+ * @menu_item: the menu item
+ * @requisition: the requisition to use as signal data.
+ *
+ * Emits the #GtkMenuItem::toggle-size-request signal on the given item.
+ */
 void
 gtk_menu_item_toggle_size_request (GtkMenuItem *menu_item,
                                    gint        *requisition)
@@ -1340,6 +1421,13 @@ gtk_menu_item_toggle_size_request (GtkMenuItem *menu_item,
   g_signal_emit (menu_item, menu_item_signals[TOGGLE_SIZE_REQUEST], 0, requisition);
 }
 
+/**
+ * gtk_menu_item_toggle_size_allocate:
+ * @menu_item: the menu item.
+ * @allocation: the allocation to use as signal data.
+ *
+ * Emits the #GtkMenuItem::toggle-size-allocate signal on the given item.
+ */
 void
 gtk_menu_item_toggle_size_allocate (GtkMenuItem *menu_item,
                                     gint         allocation)
@@ -1666,6 +1754,13 @@ gtk_menu_item_draw (GtkWidget *widget,
   return FALSE;
 }
 
+/**
+ * gtk_menu_item_select:
+ * @menu_item: the menu item
+ *
+ * Emits the #GtkMenuItem::select signal on the given item. Behaves
+ * exactly like #gtk_item_select.
+ */
 static void
 gtk_real_menu_item_select (GtkMenuItem *menu_item)
 {